---
title: AG-UI
description: Expose your Agno Agent via the AG-UI protocol
---

AG-UI, the [Agent-User Interaction Protocol](https://github.com/ag-ui-protocol/ag-ui), standardizes how AI agents connect to front-end applications.

<Note>
**Migration from Apps**: If you're migrating from `AGUIApp`, see the [v2 migration guide](/how-to/v2-migration#7-apps-interfaces) for complete steps.
</Note>

## Example usage

<Steps>
  <Step title="Install backend dependencies">

```bash
pip install ag-ui-protocol
```

  </Step>
  <Step title="Run the backend">
  Expose an Agno Agent through the AG-UI interface using `AgentOS` and `AGUI`.

```python basic.py
from agno.agent.agent import Agent
from agno.models.openai import OpenAIChat
from agno.os import AgentOS
from agno.os.interfaces.agui import AGUI

chat_agent = Agent(model=OpenAIChat(id="gpt-4o"))

agent_os = AgentOS(agents=[chat_agent], interfaces=[AGUI(agent=chat_agent)])
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="basic:app", reload=True)
```

  </Step>
  <Step title="Run the frontend">

Use Dojo (`ag-ui`'s frontend) as an advanced, customizable interface for AG-UI agents.

1. Clone: `git clone https://github.com/ag-ui-protocol/ag-ui.git`
2. Install dependencies in `/ag-ui/typescript-sdk`: `pnpm install`
3. Build the Agno package in `/ag-ui/integrations/agno`: `pnpm run build`
4. Start Dojo following the instructions in the repository.

  </Step>
  <Step title="Chat with your Agno Agent">

With Dojo running, open `http://localhost:3000` and select your Agno agent.

  </Step>
</Steps>

You can see more in our [cookbook examples](https://github.com/agno-agi/agno/tree/main/cookbook/agent_os/interfaces/agui/).

## Custom Events

Custom events you create in your tools are automatically delivered to AG-UI in the AG-UI custom event format.

**Creating custom events:**

```python
from dataclasses import dataclass
from agno.run.agent import CustomEvent

@dataclass
class CustomerProfileEvent(CustomEvent):
    customer_name: str
    customer_email: str
```

**Yielding from tools:**

```python
from agno.tools import tool

@tool()
async def get_customer_profile(customer_id: str):
    customer = fetch_customer(customer_id)
    
    yield CustomerProfileEvent(
        customer_name=customer["name"],
        customer_email=customer["email"],
    )
    
    return f"Profile retrieved for {customer['name']}"
```

Custom events are streamed in real-time to the AG-UI frontend.

See [Custom Events documentation](/concepts/agents/running-agents#custom-events) for more details.

## Core Components

- `AGUI` (interface): Wraps an Agno `Agent` or `Team` into an AG-UI compatible FastAPI router.
- `AgentOS.serve`: Serves your FastAPI app (including the AGUI router) with Uvicorn.

`AGUI` mounts protocol-compliant routes on your app.

## `AGUI` interface

Main entry point for AG-UI exposure.

### Initialization Parameters

| Parameter | Type              | Default | Description            |
| --------- | ----------------- | ------- | ---------------------- |
| `agent`   | `Optional[Agent]` | `None`  | Agno `Agent` instance. |
| `team`    | `Optional[Team]`  | `None`  | Agno `Team` instance.  |

Provide `agent` or `team`.

### Key Method

| Method       | Parameters               | Return Type | Description                                              |
| ------------ | ------------------------ | ----------- | -------------------------------------------------------- |
| `get_router` | `use_async: bool = True` | `APIRouter` | Returns the AG-UI FastAPI router and attaches endpoints. |

## Endpoints

Mounted at the interface's route prefix (root by default):

- `POST /agui`: Main entrypoint. Accepts `RunAgentInput` from `ag-ui-protocol`. Streams AG-UI events.
- `GET /status`: Health/status endpoint for the interface.

Refer to `ag-ui-protocol` docs for payload details.

## Serving your AgentOS

Use `AgentOS.serve` to run your app with Uvicorn.

### Parameters

| Parameter | Type                  | Default       | Description                            |
| --------- | --------------------- | ------------- | -------------------------------------- |
| `app`     | `Union[str, FastAPI]` | required      | FastAPI app instance or import string. |
| `host`    | `str`                 | `"localhost"` | Host to bind.                          |
| `port`    | `int`                 | `7777`        | Port to bind.                          |
| `reload`  | `bool`                | `False`       | Enable auto-reload for development.    |

See [cookbook examples](https://github.com/agno-agi/agno/tree/main/cookbook/agent_os/interfaces/agui/) for updated interface patterns.
